
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  
<!-- Mirrored from werkzeug.palletsprojects.com/en/1.0.x/wsgi/ by HTTrack Website Copier/3.x [XR&CO'2014], Tue, 15 Sep 2020 06:37:09 GMT -->
<head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>WSGI Helpers &#8212; Werkzeug Documentation (1.0.x)</title>
    <link rel="stylesheet" href="../_static/werkzeug.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" type="text/css" href="../../../../assets.readthedocs.org/static/css/badge_only.css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script async="async" type="text/javascript" src="../../../../assets.readthedocs.org/static/javascript/readthedocs-doc-embed.js"></script>
    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="index" title="Index" href="../genindex/index.html" />
    <link rel="search" title="Search" href="../search/index.html" />
    <link rel="next" title="Filesystem Utilities" href="../filesystem/index.html" />
    <link rel="prev" title="URL Routing" href="../routing/index.html" />
    <link rel="canonical" href="index.html">
  <script>DOCUMENTATION_OPTIONS.URL_ROOT = '../index.html';</script>
   
  
<!-- RTD Extra Head -->

<!-- 
Always link to the latest version, as canonical.
http://docs.readthedocs.org/en/latest/canonical.html
-->
<link rel="canonical" href="index.html" />

<link rel="stylesheet" href="../../../../assets.readthedocs.org/static/css/readthedocs-doc-embed.css" type="text/css" />

<script type="text/javascript" src="../_static/readthedocs-data.js"></script>

<!-- Add page-specific data, which must exist in the page js, not global -->
<script type="text/javascript">
READTHEDOCS_DATA['page'] = "wsgi"
READTHEDOCS_DATA['source_suffix'] = ".rst"
</script>

<script type="text/javascript" src="../../../../assets.readthedocs.org/static/javascript/readthedocs-analytics.js" async="async"></script>

<!-- end RTD <extrahead> -->
</head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex/index.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../py-modindex/index.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="../filesystem/index.html" title="Filesystem Utilities"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="../routing/index.html" title="URL Routing"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Werkzeug Documentation (1.0.x)</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="module-werkzeug.wsgi">
<span id="wsgi-helpers"></span><h1>WSGI Helpers<a class="headerlink" href="#module-werkzeug.wsgi" title="Permalink to this headline">¶</a></h1>
<p>The following classes and functions are designed to make working with
the WSGI specification easier or operate on the WSGI layer. All the
functionality from this module is available on the high-level
<a class="reference internal" href="../wrappers/index.html#wrappers"><span class="std std-ref">Request / Response classes</span></a>.</p>
<div class="section" id="iterator-stream-helpers">
<h2>Iterator / Stream Helpers<a class="headerlink" href="#iterator-stream-helpers" title="Permalink to this headline">¶</a></h2>
<p>These classes and functions simplify working with the WSGI application
iterator and the input stream.</p>
<dl class="class">
<dt id="werkzeug.wsgi.ClosingIterator">
<em class="property">class </em><code class="descclassname">werkzeug.wsgi.</code><code class="descname">ClosingIterator</code><span class="sig-paren">(</span><em>iterable</em>, <em>callbacks=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.ClosingIterator" title="Permalink to this definition">¶</a></dt>
<dd><p>The WSGI specification requires that all middlewares and gateways
respect the <cite>close</cite> callback of the iterable returned by the application.
Because it is useful to add another close action to a returned iterable
and adding a custom iterable is a boring task this class can be used for
that:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">return</span> <span class="n">ClosingIterator</span><span class="p">(</span><span class="n">app</span><span class="p">(</span><span class="n">environ</span><span class="p">,</span> <span class="n">start_response</span><span class="p">),</span> <span class="p">[</span><span class="n">cleanup_session</span><span class="p">,</span>
                                                      <span class="n">cleanup_locals</span><span class="p">])</span>
</pre></div>
</div>
<p>If there is just one close function it can be passed instead of the list.</p>
<p>A closing iterator is not needed if the application uses response objects
and finishes the processing if the response is started:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
    <span class="k">return</span> <span class="n">response</span><span class="p">(</span><span class="n">environ</span><span class="p">,</span> <span class="n">start_response</span><span class="p">)</span>
<span class="k">finally</span><span class="p">:</span>
    <span class="n">cleanup_session</span><span class="p">()</span>
    <span class="n">cleanup_locals</span><span class="p">()</span>
</pre></div>
</div>
</dd></dl>

<dl class="class">
<dt id="werkzeug.wsgi.FileWrapper">
<em class="property">class </em><code class="descclassname">werkzeug.wsgi.</code><code class="descname">FileWrapper</code><span class="sig-paren">(</span><em>file</em>, <em>buffer_size=8192</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.FileWrapper" title="Permalink to this definition">¶</a></dt>
<dd><p>This class can be used to convert a <code class="xref py py-class docutils literal notranslate"><span class="pre">file</span></code>-like object into
an iterable.  It yields <cite>buffer_size</cite> blocks until the file is fully
read.</p>
<p>You should not use this class directly but rather use the
<a class="reference internal" href="#werkzeug.wsgi.wrap_file" title="werkzeug.wsgi.wrap_file"><code class="xref py py-func docutils literal notranslate"><span class="pre">wrap_file()</span></code></a> function that uses the WSGI server’s file wrapper
support if it’s available.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
</details><p>If you’re using this object together with a <code class="xref py py-class docutils literal notranslate"><span class="pre">BaseResponse</span></code> you have
to use the <cite>direct_passthrough</cite> mode.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>file</strong> – a <code class="xref py py-class docutils literal notranslate"><span class="pre">file</span></code>-like object with a <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> method.</li>
<li><strong>buffer_size</strong> – number of bytes for one iteration.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="class">
<dt id="werkzeug.wsgi.LimitedStream">
<em class="property">class </em><code class="descclassname">werkzeug.wsgi.</code><code class="descname">LimitedStream</code><span class="sig-paren">(</span><em>stream</em>, <em>limit</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.LimitedStream" title="Permalink to this definition">¶</a></dt>
<dd><p>Wraps a stream so that it doesn’t read more than n bytes.  If the
stream is exhausted and the caller tries to get more bytes from it
<a class="reference internal" href="#werkzeug.wsgi.LimitedStream.on_exhausted" title="werkzeug.wsgi.LimitedStream.on_exhausted"><code class="xref py py-func docutils literal notranslate"><span class="pre">on_exhausted()</span></code></a> is called which by default returns an empty
string.  The return value of that function is forwarded
to the reader function.  So if it returns an empty string
<a class="reference internal" href="#werkzeug.wsgi.LimitedStream.read" title="werkzeug.wsgi.LimitedStream.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> will return an empty string as well.</p>
<p>The limit however must never be higher than what the stream can
output.  Otherwise <a class="reference internal" href="#werkzeug.wsgi.LimitedStream.readlines" title="werkzeug.wsgi.LimitedStream.readlines"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readlines()</span></code></a> will try to read past the
limit.</p>
<div class="admonition-note-on-wsgi-compliance admonition">
<p class="first admonition-title">Note on WSGI compliance</p>
<p>calls to <a class="reference internal" href="#werkzeug.wsgi.LimitedStream.readline" title="werkzeug.wsgi.LimitedStream.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> and <a class="reference internal" href="#werkzeug.wsgi.LimitedStream.readlines" title="werkzeug.wsgi.LimitedStream.readlines"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readlines()</span></code></a> are not
WSGI compliant because it passes a size argument to the
readline methods.  Unfortunately the WSGI PEP is not safely
implementable without a size argument to <a class="reference internal" href="#werkzeug.wsgi.LimitedStream.readline" title="werkzeug.wsgi.LimitedStream.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a>
because there is no EOF marker in the stream.  As a result
of that the use of <a class="reference internal" href="#werkzeug.wsgi.LimitedStream.readline" title="werkzeug.wsgi.LimitedStream.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> is discouraged.</p>
<p>For the same reason iterating over the <a class="reference internal" href="#werkzeug.wsgi.LimitedStream" title="werkzeug.wsgi.LimitedStream"><code class="xref py py-class docutils literal notranslate"><span class="pre">LimitedStream</span></code></a>
is not portable.  It internally calls <a class="reference internal" href="#werkzeug.wsgi.LimitedStream.readline" title="werkzeug.wsgi.LimitedStream.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a>.</p>
<p class="last">We strongly suggest using <a class="reference internal" href="#werkzeug.wsgi.LimitedStream.read" title="werkzeug.wsgi.LimitedStream.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> only or using the
<a class="reference internal" href="#werkzeug.wsgi.make_line_iter" title="werkzeug.wsgi.make_line_iter"><code class="xref py py-func docutils literal notranslate"><span class="pre">make_line_iter()</span></code></a> which safely iterates line-based
over a WSGI input stream.</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>stream</strong> – the stream to wrap.</li>
<li><strong>limit</strong> – the limit for the stream, must not be longer than
what the string can provide if the stream does not
end with <cite>EOF</cite> (like <cite>wsgi.input</cite>)</li>
</ul>
</td>
</tr>
</tbody>
</table>
<dl class="method">
<dt id="werkzeug.wsgi.LimitedStream.exhaust">
<code class="descname">exhaust</code><span class="sig-paren">(</span><em>chunk_size=65536</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.LimitedStream.exhaust" title="Permalink to this definition">¶</a></dt>
<dd><p>Exhaust the stream.  This consumes all the data left until the
limit is reached.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>chunk_size</strong> – the size for a chunk.  It will read the chunk
until the stream is exhausted and throw away
the results.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="attribute">
<dt id="werkzeug.wsgi.LimitedStream.is_exhausted">
<code class="descname">is_exhausted</code><a class="headerlink" href="#werkzeug.wsgi.LimitedStream.is_exhausted" title="Permalink to this definition">¶</a></dt>
<dd><p>If the stream is exhausted this attribute is <cite>True</cite>.</p>
</dd></dl>

<dl class="method">
<dt id="werkzeug.wsgi.LimitedStream.on_disconnect">
<code class="descname">on_disconnect</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.LimitedStream.on_disconnect" title="Permalink to this definition">¶</a></dt>
<dd><p>What should happen if a disconnect is detected?  The return
value of this function is returned from read functions in case
the client went away.  By default a
<a class="reference internal" href="../exceptions/index.html#werkzeug.exceptions.ClientDisconnected" title="werkzeug.exceptions.ClientDisconnected"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ClientDisconnected</span></code></a> exception is raised.</p>
</dd></dl>

<dl class="method">
<dt id="werkzeug.wsgi.LimitedStream.on_exhausted">
<code class="descname">on_exhausted</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.LimitedStream.on_exhausted" title="Permalink to this definition">¶</a></dt>
<dd><p>This is called when the stream tries to read past the limit.
The return value of this function is returned from the reading
function.</p>
</dd></dl>

<dl class="method">
<dt id="werkzeug.wsgi.LimitedStream.read">
<code class="descname">read</code><span class="sig-paren">(</span><em>size=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.LimitedStream.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Read <cite>size</cite> bytes or if size is not provided everything is read.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>size</strong> – the number of bytes read.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="werkzeug.wsgi.LimitedStream.readable">
<code class="descname">readable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.LimitedStream.readable" title="Permalink to this definition">¶</a></dt>
<dd><p>Return whether object was opened for reading.</p>
<p>If False, read() will raise OSError.</p>
</dd></dl>

<dl class="method">
<dt id="werkzeug.wsgi.LimitedStream.readline">
<code class="descname">readline</code><span class="sig-paren">(</span><em>size=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.LimitedStream.readline" title="Permalink to this definition">¶</a></dt>
<dd><p>Reads one line from the stream.</p>
</dd></dl>

<dl class="method">
<dt id="werkzeug.wsgi.LimitedStream.readlines">
<code class="descname">readlines</code><span class="sig-paren">(</span><em>size=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.LimitedStream.readlines" title="Permalink to this definition">¶</a></dt>
<dd><p>Reads a file into a list of strings.  It calls <a class="reference internal" href="#werkzeug.wsgi.LimitedStream.readline" title="werkzeug.wsgi.LimitedStream.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a>
until the file is read to the end.  It does support the optional
<cite>size</cite> argument if the underlying stream supports it for
<cite>readline</cite>.</p>
</dd></dl>

<dl class="method">
<dt id="werkzeug.wsgi.LimitedStream.tell">
<code class="descname">tell</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.LimitedStream.tell" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the position of the stream.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.9.</span></p>
</div>
</details></dd></dl>

</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.make_line_iter">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">make_line_iter</code><span class="sig-paren">(</span><em>stream</em>, <em>limit=None</em>, <em>buffer_size=10240</em>, <em>cap_at_buffer=False</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.make_line_iter" title="Permalink to this definition">¶</a></dt>
<dd><p>Safely iterates line-based over an input stream.  If the input stream
is not a <a class="reference internal" href="#werkzeug.wsgi.LimitedStream" title="werkzeug.wsgi.LimitedStream"><code class="xref py py-class docutils literal notranslate"><span class="pre">LimitedStream</span></code></a> the <cite>limit</cite> parameter is mandatory.</p>
<p>This uses the stream’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> method internally as opposite
to the <code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code> method that is unsafe and can only be used
in violation of the WSGI specification.  The same problem applies to the
<cite>__iter__</cite> function of the input stream which calls <code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code>
without arguments.</p>
<p>If you need line-by-line processing it’s strongly recommended to iterate
over the input stream using this helper function.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.11.10: </span>added support for the <cite>cap_at_buffer</cite> parameter.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.9: </span>added support for iterators as input stream.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.8: </span>This function now ensures that the limit was reached.</p>
</div>
</details><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>stream</strong> – the stream or iterate to iterate over.</li>
<li><strong>limit</strong> – the limit in bytes for the stream.  (Usually
content length.  Not necessary if the <cite>stream</cite>
is a <a class="reference internal" href="#werkzeug.wsgi.LimitedStream" title="werkzeug.wsgi.LimitedStream"><code class="xref py py-class docutils literal notranslate"><span class="pre">LimitedStream</span></code></a>.</li>
<li><strong>buffer_size</strong> – The optional buffer size.</li>
<li><strong>cap_at_buffer</strong> – if this is set chunks are split if they are longer
than the buffer size.  Internally this is implemented
that the buffer size might be exhausted by a factor
of two however.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.make_chunk_iter">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">make_chunk_iter</code><span class="sig-paren">(</span><em>stream</em>, <em>separator</em>, <em>limit=None</em>, <em>buffer_size=10240</em>, <em>cap_at_buffer=False</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.make_chunk_iter" title="Permalink to this definition">¶</a></dt>
<dd><p>Works like <a class="reference internal" href="#werkzeug.wsgi.make_line_iter" title="werkzeug.wsgi.make_line_iter"><code class="xref py py-func docutils literal notranslate"><span class="pre">make_line_iter()</span></code></a> but accepts a separator
which divides chunks.  If you want newline based processing
you should use <a class="reference internal" href="#werkzeug.wsgi.make_line_iter" title="werkzeug.wsgi.make_line_iter"><code class="xref py py-func docutils literal notranslate"><span class="pre">make_line_iter()</span></code></a> instead as it
supports arbitrary newline markers.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.11.10: </span>added support for the <cite>cap_at_buffer</cite> parameter.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.9: </span>added support for iterators as input stream.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.8.</span></p>
</div>
</details><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>stream</strong> – the stream or iterate to iterate over.</li>
<li><strong>separator</strong> – the separator that divides chunks.</li>
<li><strong>limit</strong> – the limit in bytes for the stream.  (Usually
content length.  Not necessary if the <cite>stream</cite>
is otherwise already limited).</li>
<li><strong>buffer_size</strong> – The optional buffer size.</li>
<li><strong>cap_at_buffer</strong> – if this is set chunks are split if they are longer
than the buffer size.  Internally this is implemented
that the buffer size might be exhausted by a factor
of two however.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.wrap_file">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">wrap_file</code><span class="sig-paren">(</span><em>environ</em>, <em>file</em>, <em>buffer_size=8192</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.wrap_file" title="Permalink to this definition">¶</a></dt>
<dd><p>Wraps a file.  This uses the WSGI server’s file wrapper if available
or otherwise the generic <a class="reference internal" href="#werkzeug.wsgi.FileWrapper" title="werkzeug.wsgi.FileWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileWrapper</span></code></a>.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
</details><p>If the file wrapper from the WSGI server is used it’s important to not
iterate over it from inside the application but to pass it through
unchanged.  If you want to pass out a file wrapper inside a response
object you have to set <code class="xref py py-attr docutils literal notranslate"><span class="pre">direct_passthrough</span></code> to <cite>True</cite>.</p>
<p>More information about file wrappers are available in <span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0333"><strong>PEP 333</strong></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>file</strong> – a <code class="xref py py-class docutils literal notranslate"><span class="pre">file</span></code>-like object with a <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> method.</li>
<li><strong>buffer_size</strong> – number of bytes for one iteration.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</div>
<div class="section" id="environ-helpers">
<h2>Environ Helpers<a class="headerlink" href="#environ-helpers" title="Permalink to this headline">¶</a></h2>
<p>These functions operate on the WSGI environment.  They extract useful
information or perform common manipulations:</p>
<dl class="function">
<dt id="werkzeug.wsgi.get_host">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">get_host</code><span class="sig-paren">(</span><em>environ</em>, <em>trusted_hosts=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.get_host" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the host for the given WSGI environment. This first checks
the <code class="docutils literal notranslate"><span class="pre">Host</span></code> header. If it’s not present, then <code class="docutils literal notranslate"><span class="pre">SERVER_NAME</span></code> and
<code class="docutils literal notranslate"><span class="pre">SERVER_PORT</span></code> are used. The host will only contain the port if it
is different than the standard port for the protocol.</p>
<p>Optionally, verify that the host is trusted using
<a class="reference internal" href="#werkzeug.wsgi.host_is_trusted" title="werkzeug.wsgi.host_is_trusted"><code class="xref py py-func docutils literal notranslate"><span class="pre">host_is_trusted()</span></code></a> and raise a
<a class="reference internal" href="../exceptions/index.html#werkzeug.exceptions.SecurityError" title="werkzeug.exceptions.SecurityError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SecurityError</span></code></a> if it is not.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>environ</strong> – The WSGI environment to get the host from.</li>
<li><strong>trusted_hosts</strong> – A list of trusted hosts.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">Host, with port if necessary.</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises:</th><td class="field-body"><p class="first last"><a class="reference internal" href="../exceptions/index.html#werkzeug.exceptions.SecurityError" title="werkzeug.exceptions.SecurityError"><strong>SecurityError</strong></a> – If the host is not
trusted.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.get_content_length">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">get_content_length</code><span class="sig-paren">(</span><em>environ</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.get_content_length" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the content length from the WSGI environment as
integer. If it’s not available or chunked transfer encoding is used,
<code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.9.</span></p>
</div>
</details><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>environ</strong> – the WSGI environ to fetch the content length from.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.get_input_stream">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">get_input_stream</code><span class="sig-paren">(</span><em>environ</em>, <em>safe_fallback=True</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.get_input_stream" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the input stream from the WSGI environment and wraps it
in the most sensible way possible. The stream returned is not the
raw WSGI stream in most cases but one that is safe to read from
without taking into account the content length.</p>
<p>If content length is not set, the stream will be empty for safety reasons.
If the WSGI server supports chunked or infinite streams, it should set
the <code class="docutils literal notranslate"><span class="pre">wsgi.input_terminated</span></code> value in the WSGI environ to indicate that.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.9.</span></p>
</div>
</details><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>environ</strong> – the WSGI environ to fetch the stream from.</li>
<li><strong>safe_fallback</strong> – use an empty stream as a safe fallback when the
content length is not set. Disabling this allows infinite streams,
which can be a denial-of-service risk.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.get_current_url">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">get_current_url</code><span class="sig-paren">(</span><em>environ</em>, <em>root_only=False</em>, <em>strip_querystring=False</em>, <em>host_only=False</em>, <em>trusted_hosts=None</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.get_current_url" title="Permalink to this definition">¶</a></dt>
<dd><p>A handy helper function that recreates the full URL as IRI for the
current request or parts of it.  Here’s an example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">werkzeug.test</span> <span class="k">import</span> <span class="n">create_environ</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">env</span> <span class="o">=</span> <span class="n">create_environ</span><span class="p">(</span><span class="s2">&quot;/?param=foo&quot;</span><span class="p">,</span> <span class="s2">&quot;http://localhost/script&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">get_current_url</span><span class="p">(</span><span class="n">env</span><span class="p">)</span>
<span class="go">&#39;http://localhost/script/?param=foo&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">get_current_url</span><span class="p">(</span><span class="n">env</span><span class="p">,</span> <span class="n">root_only</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">&#39;http://localhost/script/&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">get_current_url</span><span class="p">(</span><span class="n">env</span><span class="p">,</span> <span class="n">host_only</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">&#39;http://localhost/&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">get_current_url</span><span class="p">(</span><span class="n">env</span><span class="p">,</span> <span class="n">strip_querystring</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">&#39;http://localhost/script/&#39;</span>
</pre></div>
</div>
<p>This optionally it verifies that the host is in a list of trusted hosts.
If the host is not in there it will raise a
<a class="reference internal" href="../exceptions/index.html#werkzeug.exceptions.SecurityError" title="werkzeug.exceptions.SecurityError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SecurityError</span></code></a>.</p>
<p>Note that the string returned might contain unicode characters as the
representation is an IRI not an URI.  If you need an ASCII only
representation you can use the <a class="reference internal" href="../urls/index.html#werkzeug.urls.iri_to_uri" title="werkzeug.urls.iri_to_uri"><code class="xref py py-func docutils literal notranslate"><span class="pre">iri_to_uri()</span></code></a>
function:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">werkzeug.urls</span> <span class="k">import</span> <span class="n">iri_to_uri</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">iri_to_uri</span><span class="p">(</span><span class="n">get_current_url</span><span class="p">(</span><span class="n">env</span><span class="p">))</span>
<span class="go">&#39;http://localhost/script/?param=foo&#39;</span>
</pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>environ</strong> – the WSGI environment to get the current URL from.</li>
<li><strong>root_only</strong> – set <cite>True</cite> if you only want the root URL.</li>
<li><strong>strip_querystring</strong> – set to <cite>True</cite> if you don’t want the querystring.</li>
<li><strong>host_only</strong> – set to <cite>True</cite> if the host URL should be returned.</li>
<li><strong>trusted_hosts</strong> – a list of trusted hosts, see <a class="reference internal" href="#werkzeug.wsgi.host_is_trusted" title="werkzeug.wsgi.host_is_trusted"><code class="xref py py-func docutils literal notranslate"><span class="pre">host_is_trusted()</span></code></a>
for more information.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.get_query_string">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">get_query_string</code><span class="sig-paren">(</span><em>environ</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.get_query_string" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the <cite>QUERY_STRING</cite> from the WSGI environment.  This also takes
care about the WSGI decoding dance on Python 3 environments as a
native string.  The string returned will be restricted to ASCII
characters.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.9.</span></p>
</div>
</details><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>environ</strong> – the WSGI environment object to get the query string from.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.get_script_name">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">get_script_name</code><span class="sig-paren">(</span><em>environ</em>, <em>charset='utf-8'</em>, <em>errors='replace'</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.get_script_name" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the <cite>SCRIPT_NAME</cite> from the WSGI environment and properly
decodes it.  This also takes care about the WSGI decoding dance
on Python 3 environments.  if the <cite>charset</cite> is set to <cite>None</cite> a
bytestring is returned.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.9.</span></p>
</div>
</details><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>environ</strong> – the WSGI environment object to get the path from.</li>
<li><strong>charset</strong> – the charset for the path, or <cite>None</cite> if no
decoding should be performed.</li>
<li><strong>errors</strong> – the decoding error handling.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.get_path_info">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">get_path_info</code><span class="sig-paren">(</span><em>environ</em>, <em>charset='utf-8'</em>, <em>errors='replace'</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.get_path_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the <cite>PATH_INFO</cite> from the WSGI environment and properly
decodes it.  This also takes care about the WSGI decoding dance
on Python 3 environments.  if the <cite>charset</cite> is set to <cite>None</cite> a
bytestring is returned.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.9.</span></p>
</div>
</details><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>environ</strong> – the WSGI environment object to get the path from.</li>
<li><strong>charset</strong> – the charset for the path info, or <cite>None</cite> if no
decoding should be performed.</li>
<li><strong>errors</strong> – the decoding error handling.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.pop_path_info">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">pop_path_info</code><span class="sig-paren">(</span><em>environ</em>, <em>charset='utf-8'</em>, <em>errors='replace'</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.pop_path_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Removes and returns the next segment of <cite>PATH_INFO</cite>, pushing it onto
<cite>SCRIPT_NAME</cite>.  Returns <cite>None</cite> if there is nothing left on <cite>PATH_INFO</cite>.</p>
<p>If the <cite>charset</cite> is set to <cite>None</cite> a bytestring is returned.</p>
<p>If there are empty segments (<code class="docutils literal notranslate"><span class="pre">'/foo//bar</span></code>) these are ignored but
properly pushed to the <cite>SCRIPT_NAME</cite>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">env</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;SCRIPT_NAME&#39;</span><span class="p">:</span> <span class="s1">&#39;/foo&#39;</span><span class="p">,</span> <span class="s1">&#39;PATH_INFO&#39;</span><span class="p">:</span> <span class="s1">&#39;/a/b&#39;</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pop_path_info</span><span class="p">(</span><span class="n">env</span><span class="p">)</span>
<span class="go">&#39;a&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">env</span><span class="p">[</span><span class="s1">&#39;SCRIPT_NAME&#39;</span><span class="p">]</span>
<span class="go">&#39;/foo/a&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pop_path_info</span><span class="p">(</span><span class="n">env</span><span class="p">)</span>
<span class="go">&#39;b&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">env</span><span class="p">[</span><span class="s1">&#39;SCRIPT_NAME&#39;</span><span class="p">]</span>
<span class="go">&#39;/foo/a/b&#39;</span>
</pre></div>
</div>
<details class="changelog">
<summary>Changelog</summary><div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.9: </span>The path is now decoded and a charset and encoding
parameter can be provided.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
</details><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>environ</strong> – the WSGI environment that is modified.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.peek_path_info">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">peek_path_info</code><span class="sig-paren">(</span><em>environ</em>, <em>charset='utf-8'</em>, <em>errors='replace'</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.peek_path_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the next segment on the <cite>PATH_INFO</cite> or <cite>None</cite> if there
is none.  Works like <a class="reference internal" href="#werkzeug.wsgi.pop_path_info" title="werkzeug.wsgi.pop_path_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">pop_path_info()</span></code></a> without modifying the
environment:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">env</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;SCRIPT_NAME&#39;</span><span class="p">:</span> <span class="s1">&#39;/foo&#39;</span><span class="p">,</span> <span class="s1">&#39;PATH_INFO&#39;</span><span class="p">:</span> <span class="s1">&#39;/a/b&#39;</span><span class="p">}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">peek_path_info</span><span class="p">(</span><span class="n">env</span><span class="p">)</span>
<span class="go">&#39;a&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">peek_path_info</span><span class="p">(</span><span class="n">env</span><span class="p">)</span>
<span class="go">&#39;a&#39;</span>
</pre></div>
</div>
<p>If the <cite>charset</cite> is set to <cite>None</cite> a bytestring is returned.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.9: </span>The path is now decoded and a charset and encoding
parameter can be provided.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
</details><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>environ</strong> – the WSGI environment that is checked.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.extract_path_info">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">extract_path_info</code><span class="sig-paren">(</span><em>environ_or_baseurl</em>, <em>path_or_url</em>, <em>charset='utf-8'</em>, <em>errors='werkzeug.url_quote'</em>, <em>collapse_http_schemes=True</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.extract_path_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Extracts the path info from the given URL (or WSGI environment) and
path.  The path info returned is a unicode string, not a bytestring
suitable for a WSGI environment.  The URLs might also be IRIs.</p>
<p>If the path info could not be determined, <cite>None</cite> is returned.</p>
<p>Some examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">extract_path_info</span><span class="p">(</span><span class="s1">&#39;http://example.com/app&#39;</span><span class="p">,</span> <span class="s1">&#39;/app/hello&#39;</span><span class="p">)</span>
<span class="go">u&#39;/hello&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">extract_path_info</span><span class="p">(</span><span class="s1">&#39;http://example.com/app&#39;</span><span class="p">,</span>
<span class="gp">... </span>                  <span class="s1">&#39;https://example.com/app/hello&#39;</span><span class="p">)</span>
<span class="go">u&#39;/hello&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">extract_path_info</span><span class="p">(</span><span class="s1">&#39;http://example.com/app&#39;</span><span class="p">,</span>
<span class="gp">... </span>                  <span class="s1">&#39;https://example.com/app/hello&#39;</span><span class="p">,</span>
<span class="gp">... </span>                  <span class="n">collapse_http_schemes</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span> <span class="ow">is</span> <span class="kc">None</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Instead of providing a base URL you can also pass a WSGI environment.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>environ_or_baseurl</strong> – a WSGI environment dict, a base URL or
base IRI.  This is the root of the
application.</li>
<li><strong>path_or_url</strong> – an absolute path from the server root, a
relative path (in which case it’s the path info)
or a full URL.  Also accepts IRIs and unicode
parameters.</li>
<li><strong>charset</strong> – the charset for byte data in URLs</li>
<li><strong>errors</strong> – the error handling on decode</li>
<li><strong>collapse_http_schemes</strong> – if set to <cite>False</cite> the algorithm does
not assume that http and https on the
same server point to the same
resource.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<details class="changelog">
<summary>Changelog</summary><div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.15: </span>The <code class="docutils literal notranslate"><span class="pre">errors</span></code> parameter defaults to leaving invalid bytes
quoted instead of replacing them.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
</details></dd></dl>

<dl class="function">
<dt id="werkzeug.wsgi.host_is_trusted">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">host_is_trusted</code><span class="sig-paren">(</span><em>hostname</em>, <em>trusted_list</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.host_is_trusted" title="Permalink to this definition">¶</a></dt>
<dd><p>Checks if a host is trusted against a list.  This also takes care
of port normalization.</p>
<details class="changelog">
<summary>Changelog</summary><div class="versionadded">
<p><span class="versionmodified">New in version 0.9.</span></p>
</div>
</details><table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>hostname</strong> – the hostname to check</li>
<li><strong>trusted_list</strong> – a list of hostnames to check against.  If a
hostname starts with a dot it will match against
all subdomains as well.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

</div>
<div class="section" id="convenience-helpers">
<h2>Convenience Helpers<a class="headerlink" href="#convenience-helpers" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="werkzeug.wsgi.responder">
<code class="descclassname">werkzeug.wsgi.</code><code class="descname">responder</code><span class="sig-paren">(</span><em>f</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.wsgi.responder" title="Permalink to this definition">¶</a></dt>
<dd><p>Marks a function as responder.  Decorate a function with it and it
will automatically call the return value as WSGI application.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@responder</span>
<span class="k">def</span> <span class="nf">application</span><span class="p">(</span><span class="n">environ</span><span class="p">,</span> <span class="n">start_response</span><span class="p">):</span>
    <span class="k">return</span> <span class="n">Response</span><span class="p">(</span><span class="s1">&#39;Hello World!&#39;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="werkzeug.testapp.test_app">
<code class="descclassname">werkzeug.testapp.</code><code class="descname">test_app</code><span class="sig-paren">(</span><em>environ</em>, <em>start_response</em><span class="sig-paren">)</span><a class="headerlink" href="#werkzeug.testapp.test_app" title="Permalink to this definition">¶</a></dt>
<dd><p>Simple test application that dumps the environment.  You can use
it to check if Werkzeug is working properly:</p>
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">werkzeug.serving</span> <span class="kn">import</span> <span class="n">run_simple</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">werkzeug.testapp</span> <span class="kn">import</span> <span class="n">test_app</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">run_simple</span><span class="p">(</span><span class="s1">&#39;localhost&#39;</span><span class="p">,</span> <span class="mi">3000</span><span class="p">,</span> <span class="n">test_app</span><span class="p">)</span>
<span class="go"> * Running on http://localhost:3000/</span>
</pre></div>
</div>
<p>The application displays important information from the WSGI environment,
the Python interpreter and the installed libraries.</p>
</dd></dl>

</div>
<div class="section" id="bytes-strings-and-encodings">
<h2>Bytes, Strings, and Encodings<a class="headerlink" href="#bytes-strings-and-encodings" title="Permalink to this headline">¶</a></h2>
<p>The WSGI environment on Python 3 works slightly different than it does
on Python 2. Werkzeug hides the differences from you if you use the
higher level APIs.</p>
<p>The WSGI specification (<a class="reference external" href="https://www.python.org/dev/peps/pep-3333/#unicode-issues">PEP 3333</a>) decided to always use the native
<code class="docutils literal notranslate"><span class="pre">str</span></code> type. On Python 2 this means the raw bytes are passed through
and can be decoded directly. On Python 3, however, the raw bytes are
always decoded using the ISO-8859-1 charset to produce a Unicode string.</p>
<p>Python 3 Unicode strings in the WSGI environment are restricted to
ISO-8859-1 code points. If a string read from the environment might
contain characters outside that charset, it must first be decoded to
bytes as ISO-8859-1, then encoded to a Unicode string using the proper
charset (typically UTF-8). The reverse is done when writing to the
environ. This is known as the “WSGI encoding dance”.</p>
<p>Werkzeug provides functions to deal with this automatically so that you
don’t need to be aware of the inner workings. Use the functions on this
page as well as <a class="reference internal" href="../datastructures/index.html#werkzeug.datastructures.EnvironHeaders" title="werkzeug.datastructures.EnvironHeaders"><code class="xref py py-func docutils literal notranslate"><span class="pre">EnvironHeaders()</span></code></a> to read
data out of the WSGI environment.</p>
<p>Applications should avoid manually creating or modifying a WSGI
environment unless they take care of the proper encoding or decoding
step. All high level interfaces in Werkzeug will apply the encoding and
decoding as necessary.</p>
</div>
<div class="section" id="raw-request-uri-and-path-encoding">
<h2>Raw Request URI and Path Encoding<a class="headerlink" href="#raw-request-uri-and-path-encoding" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">PATH_INFO</span></code> in the environ is the path value after
percent-decoding. For example, the raw path <code class="docutils literal notranslate"><span class="pre">/hello%2fworld</span></code> would
show up from the WSGI server to Werkzeug as <code class="docutils literal notranslate"><span class="pre">/hello/world</span></code>. This loses
the information that the slash was a raw character as opposed to a path
separator.</p>
<p>The WSGI specification (<a class="reference external" href="https://www.python.org/dev/peps/pep-3333/#unicode-issues">PEP 3333</a>) does not provide a way to get the
original value, so it is impossible to route some types of data in the
path. The most compatible way to work around this is to send problematic
data in the query string instead of the path.</p>
<p>However, many WSGI servers add a non-standard environ key with the raw
path. To match this behavior, Werkzeug’s test client and development
server will add the raw value to both the <code class="docutils literal notranslate"><span class="pre">REQUEST_URI</span></code> and
<code class="docutils literal notranslate"><span class="pre">RAW_URI</span></code> keys. If you want to route based on this value, you can use
middleware to replace <code class="docutils literal notranslate"><span class="pre">PATH_INFO</span></code> in the environ before it reaches the
application. However, keep in mind that these keys are non-standard and
not guaranteed to be present.</p>
</div>
</div>


          </div>
        </div>
      </div>
  <span id="sidebar-top"></span>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  
    
            <p class="logo"><a href="../index.html">
              <img class="logo" src="../_static/werkzeug.png" alt="Logo"/>
            </a></p>
  

  <h3>Contents</h3>
  <ul>
<li><a class="reference internal" href="#">WSGI Helpers</a><ul>
<li><a class="reference internal" href="#iterator-stream-helpers">Iterator / Stream Helpers</a></li>
<li><a class="reference internal" href="#environ-helpers">Environ Helpers</a></li>
<li><a class="reference internal" href="#convenience-helpers">Convenience Helpers</a></li>
<li><a class="reference internal" href="#bytes-strings-and-encodings">Bytes, Strings, and Encodings</a></li>
<li><a class="reference internal" href="#raw-request-uri-and-path-encoding">Raw Request URI and Path Encoding</a></li>
</ul>
</li>
</ul>
<h3>Navigation</h3>
<ul>
  <li><a href="../index.html">Overview</a>
    <ul>
          <li>Previous: <a href="../routing/index.html" title="previous chapter">URL Routing</a>
          <li>Next: <a href="../filesystem/index.html" title="next chapter">Filesystem Utilities</a>
    </ul>
  </li>
</ul>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="https://werkzeug.palletsprojects.com/en/1.0.x/search/" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  
    <div class="footer" role="contentinfo">
        &#169; Copyright 2007 Pallets.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
    </div>
    <script>
      if (typeof READTHEDOCS_DATA !== 'undefined') {
        if (!READTHEDOCS_DATA.features) {
          READTHEDOCS_DATA.features = {};
        }
        READTHEDOCS_DATA.features.docsearch_disabled = true;
      }
    </script>

  </body>

<!-- Mirrored from werkzeug.palletsprojects.com/en/1.0.x/wsgi/ by HTTrack Website Copier/3.x [XR&CO'2014], Tue, 15 Sep 2020 06:37:09 GMT -->
</html>